Mackerel API を利用してオーガニゼーションへ招待してみる

はじめに

みなさん、Mackerel 使ってますか！（挨拶）

Mackerel には mkr という CLI が用意されていますが、それだけではなく REST API も存在します。

• CLIツール mkr を使う - Mackerel ヘルプ
• Mackerel API ドキュメント（v0）

mkr では出来ないけれど API なら可能、という操作もあるので、これが使えると利用方法に幅が出ますね。REST API は curl コマンドを使って簡単に叩くことができるので、ここでは試しに、既存のオーガニゼーションへの招待を CLI から実行 してみたいと思います。下記のドキュメントに書いてある操作です。

• 他のユーザをMackerelに招待する - Mackerel ヘルプ

これができれば Web UI に頼らず、例えば「新メンバー参画時に実行する環境準備用のスクリプトの最後で自動的に招待する」といったことが出来るようになるので、利便性があがりそうです。

「招待の作成」 API

今回使用する API のドキュメントはこちらになります：

• 招待の作成 - 招待 - Mackerel API ドキュメント (v0)

API ドキュメントのトップ（概要） に書いてある情報とあわせて読むと、以下のようにすれば良いことがわかります。

• REST API の URL は https://api.mackerelio.com/api/v0/invitations
  • Mackerel for KCPS 利用の場合は https://kcps-mackerel.io/api/v0/invitations
• Content-Type は application/json
• X-Api-Key ヘッダに API キーを記述
  • API キーは Read/Write のものを使用する
  • APIキーはダッシュボードのAPIキータブで確認
    • -> https://mackerel.io/my?tab=apikeys
• メソッドは POST
  • 入力内容を JSON 形式で POST してやれば良い
• 入力に必要なキーは email と authority
  • 必須でないキーは、ドキュメント上 DESCRIPTION に「[optional]」と付記してあるので判断できます

入力の JSON サンプルはインデントされた状態で記載されていますが、「RFCに準拠」していれば良いとのことで、つまり下記のようにコンパクト化したものも ok ということですね。

{"email":"example@example.com","authority":"viewer"}

また authority キーに指定する値は、 ユーザー権限 - Mackerel ヘルプ のドキュメントと併せて読むことで、下記と判断がつきます。

authority	権限
manager	管理者
collaborator	一般ユーザー
viewer	閲覧者

つまり上記のサンプル JSON は、「 閲覧者権限で example@example.com を招待する 」という内容になります。

コマンドライン

上記を考慮しつつ、実際に curl のコマンドラインを組み立ててみます。見た目のわかりやすさと再利用性を考えて改行いれたり変数化したりしてますが、実際に使う場合は展開しても（もちろん）問題ありません。

MACKEREL_APIKEY=<APIキー文字列>
MAIL_ADDRESS=<招待したいメールアドレス>
AUTHORITY="viewer"

curl -sS \
    -H "X-Api-Key: ${MACKEREL_APIKEY}" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{"email":"'${MAIL_ADDRESS}'","authority":"'${AUTHORITY}'"}' \
    https://api.mackerelio.com/api/v0/invitations

なお、curl は GET か POST かを自動判別する機能があるため、上記の例であれば 8 行目（ -X POST \ の行）は本来は不要です。ただ PUT や DELETE 系の API を叩く場合は忘れずに指定する必要がありますので注意してください。

ここで実行した「招待」が現在どういう状態になっているか（招待中か否か）は、同じ API を（今度は）GET で叩くことで確認可能です。今度は HTTP メソッドの指定や Content-Type ヘッダは不要ですね。

MACKEREL_APIKEY=<APIキー文字列>

curl -sS \
    -H "X-Api-Key: ${MACKEREL_APIKEY}" \
    https://api.mackerelio.com/api/v0/invitations

API から送られてくる返答は JSON なので、jq などを通して整形・シンタクスハイライトしてあげると分かりやすいでしょう。

先に実行した「招待」の状況が確認できたでしょうか？

ちなみに

上の例ではさくっと POST してしまいましたが、本来は Write 操作を伴う作業では、API キーの指定は慎重に行いたいものです。

例えば 1 文字コピペミスした、Write 権限のない API を指定してしまった等であれば、処理がエラーになる程度ですむので良いのですけど、オーガニゼーションを間違えると（状況により）大変なことになります。正しいかどうかは curl 実行前に確認したいですよね。

それではその確認を、 mkr org コマンドで実施しましょう。上記の例だと MACKEREL_APIKEY という変数を使っているので、そのまま mkr コマンドで活用できます。

export MACKEREL_APIKEY
mkr org

• mkr org コマンドでオーガニゼーション名を取得できるようにしました - カスタムダッシュボードをリニューアルしました ほか - Mackerel ブログ #mackerelio

これを curl で行う場合は下記になります。 mkr がインストールされていない環境で実行する場合などであれば、こちらがいいですね。

curl -sS \
    -H "X-Api-Key: ${MACKEREL_APIKEY}" \
    https://api.mackerelio.com/api/v0/org

注意

API 直叩きというと、そのコール数の上限（あるいは課金）が気になるところかと思います。'19/02 時点では、公式ドキュメントにその記述を見つけることはできません（あったらごめんなさい、こっそり教えてください）。

ただし、サービスメトリック投稿 API にはエンドポイント毎の毎分投稿回数に上限がかけられています。そもそも mkr コマンドも内部的には Mackerel API を使っているものと思われますし、常識的な範囲内で利用する分には気にする必要はないと思います。

• サービスメトリック投稿APIに投稿数制限を設けました - AWSインテグレーションがAPI Gateway に対応しました ほか - Mackerel ブログ #mackerelio

ただし、あまりに高頻度でのアクセスを行って Mackerel のインフラに影響が及ぶような場合はその限りではない（DoS と判断されてしまう）でしょうから、あくまで紳士的に 利用するようにしてください。

おまけ：APIキーを mackerel-agent.conf から取得する

既に mackerel-agent や mkr コマンドを使っている環境の場合、API キーは mackerel-agent.conf ファイルに記述されていると思うのでそちらを使いたくなりますよね。一手間かかりますが、下記のようにすることで取り込むことが可能です。

ついでにホスト ID もファイル（ /var/lib/mackerel-agent/id ）から取り込んで、自分（ホスト）自身のステータスを「メンテナンス」に変更してみましょう。

# mackerel-agent.conf から APIキーの値を取得
MACKEREL_APIKEY=$(
  MACKEREL_AGENT_CONF=/etc/mackerel-agent/mackerel-agent.conf
  awk -F\" '/^apikey =/{print $2}' $MACKEREL_AGENT_CONF
)
# /var/lib/mackerel-agent/id からホストIDを取得
MACKEREL_HOSTID=$(
  cat /var/lib/mackerel-agent/id
)

# API を叩いてホストステータスを maintenance に変更
HOST_STATUS=maintenance
curl -sS \
    -H "X-Api-Key: ${MACKEREL_APIKEY}" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{"status":"'${HOST_STATUS}'"}' \
    https://api.mackerelio.com/api/v0/hosts/${MACKEREL_HOSTID}/status

もちろんこれは、下記 mkr コマンドと同等です。無理に片方によせず、状況に応じて使い分け/工夫すると良いかと思います。

mkr update -st maintenance

まとめ

Mackerel API を curl で叩く方法をご紹介しました。

個人的には AWS インテグレーション設定を叩く API などが欲しくなるのですが、それでも Web UI を使わなくても出来ることが広がるので、積極的に使い倒して行きたいですね！